package org.vaadin.nf4v.core.handler;

import org.vaadin.nf4v.core.navigation.InvalidUriException;
import org.vaadin.nf4v.core.navigation.target.NavigationTarget;

/**
 * Handler is responsible for parsing and creating of page uri string.
 * E.g. for uri "order/10/12/34" it should detect page uri (order) and find page class for this uri in
 * current context. Parameters part should be stored as not parsed ("10/12/34").
 *
 * In reverse case it should combine page uri string "order/10/12/34" from navigation target (aka from known page).
 * Again it should not create param string for itself.
 *
 * Separation of parameters parsing provides more flexibility for parameters handling.
 * Uri handler may be registered only for context, but parameter handlers may be different for each page!
 *
 * OVERRIDING: may be overridden for context.
 */
public interface UriHandler extends Handler{
    /**
     * Parses uri into valid target (main function - detect target page)
     * Method don't parse actual parameters string, just cuts uri into page uri and parameters string
     * and stores it as string inside target for later processing (by ParamResolver)
     *
     * @param fragment uri fragment (page uri with parameters)
     * @return parsed target object
     * @throws InvalidUriException when it is not possible to determine exact page by uri
     */
    NavigationTarget parseUri(String fragment) throws InvalidUriException;

    /**
     * Creates page uri for provided navigation target.
     * Note: parameters string inside target object should be prepared by ParamResolver.
     *
     * @param target navigation target
     * @return composed target uri
     */
    String composeUri(NavigationTarget target);
}
